gesture: Document pitfalls on foreign gesture state changes

Add some docs/example about the possible event handling ordering issues
that may appear on GtkGesture::begin between multiple gesture groups.
Mostly relevant for state changes.

diff --git a/gtk/gtkgesture.c b/gtk/gtkgesture.c
index fb913aa26059f4105cb3dc3766eb63030661afec..cfdd3d0699827b68f1ff4da6fb0cec82f2c92690 100644 (file)
--- a/gtk/gtkgesture.c
+++ b/gtk/gtkgesture.c
@@ -904,6 +904,37 @@ gtk_gesture_get_sequence_state (GtkGesture       *gesture,
  * * None → Claimed
  * * None → Claimed → Denied
  *
+ * Note: Due to event handling ordering, it may be unsafe to
+ * set the state on another gesture within a #GtkGesture::begin
+ * signal handler, as the callback might be executed before
+ * the other gesture knows about the sequence. A safe way to
+ * perform this could be:
+ *
+ * |[
+ * static void
+ * first_gesture_begin_cb (GtkGesture       *first_gesture,
+ *                         GdkEventSequence *sequence,
+ *                         gpointer          user_data)
+ * {
+ *   gtk_gesture_set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_ACCEPTED);
+ *   gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
+ * }
+ *
+ * static void
+ * second_gesture_begin_cb (GtkGesture       *second_gesture,
+ *                          GdkEventSequence *sequence,
+ *                          gpointer          user_data)
+ * {
+ *   if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_ACCEPTED)
+ *     gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
+ * }
+ * ]|
+ *
+ * If both gestures are in the same group, just set the state on
+ * the gesture emitting the event, the sequence will be already
+ * be initialized to the group's global state when the second
+ * gesture processes the event.
+ *
  * Returns: %TRUE if @sequence is handled by @gesture,
  *          and the state is changed successfully
  *